Skip to main content

Remote credentials

A remote credential lets ApertureDB read media from an external S3 bucket, Google Cloud Storage bucket, or HTTPS origin. It is separate from a database user’s password and from the server credentials used to store its own database.

Register one credential per origin​

Use CreateCredential with origin and key. An origin is s3://bucket, gs://bucket, or https://media.example.com. The scheme selects the provider.

Origins must not contain paths, trailing slashes, query strings, or fragments. HTTPS hostnames are lowercased and port 443 is omitted during registration. Nondefault HTTPS ports identify distinct origins. Object-storage bucket spelling is preserved. Register each bucket separately, even when several use the same key.

[{"CreateCredential": {
  "origin": "https://media.example.com",
  "key": {"bearer_token": "<origin-token>"}
}}]

An anonymous HTTPS origin still needs a credential, with key: {}. key describes provider fields and HTTPS restrictions. Registration checks the required fields without contacting the provider. Verify access by retrieving a small object afterward. GetCredentials lists registered origins without returning keys.

Use credentials in a later query​

Register the credential and wait for success before submitting a query that reads media from that origin. An AddBlob, AddImage, or AddVideo command accepts a full url instead of an input blob. The object stays at that location. ApertureDB uses the registered credential for the origin; URLs into its own storage bucket are refused.

Creating or changing a credential in the same query as a media command does not change the key used for that query’s media reads, even if the credential command comes first. Submit the credential change separately when the media command needs the new key.

Retrieving media requires a registered credential. Returning a stored URL as a property without fetching its content does not.

Rotate and remove credentials​

UpdateCredential replaces the complete key for an existing origin. Wait for the update to succeed before submitting queries that should use the new key. A request already underway may finish using the previous key. The remote provider can independently revoke a key and cause those reads to fail.

RemoveCredential prevents later requests from reading media at that origin until a credential is registered again. Removal leaves the remote objects and their database records intact. Requests already underway may still finish. Creating, updating, or removing a credential succeeds or rolls back with the query’s other database changes.

In a cluster, other replicas may take a short time to reflect credential changes.

Read subsequent batch pages​

Each page request needs a valid session and access to the remote media it returns. Updating or removing a credential affects subsequent page requests, so a later page may fail even when an earlier page succeeded. Restore access before retrying the page. See batch for batch usage and limits.

See Configuration File for remote connection and download limits.

Upgrade existing registrations​

Update client queries to identify registrations with origin instead of name. CreateCredential takes origin and key; UpdateCredential replaces that origin’s entire key. The old service, resources, add_resources, and remove_resources fields are no longer accepted.

Usable registrations are imported automatically during a supported upgrade. Each bucket or HTTPS origin becomes a separate registration. Entries with paths, trailing slashes, or malformed keys are skipped with a startup warning. Path entries did not grant access in the previous release and are not expanded to whole-bucket access during the upgrade.

If several registrations refer to the same origin, the first structurally valid key in credential-name order is retained. Import does not contact the provider to check whether a key is still accepted. Review the origins with GetCredentials, use UpdateCredential to set the intended key where registrations overlapped, and test a media read. Use CreateCredential for any missing origin.

After upgrading, manage credentials through the API; editing the old credential files no longer changes access.